Skip to main content

Updating information in the terminals

Endpoint for this service is:

https://api.sfey.com/device-api/v1/update/{terminalSn}/type/{terminalTypeName}

Endpoint is used for updating following data in the terminal:

  • Deny list
  • Permanent stoplist
  • Transit/Terminal keys for travel cards
  • EMV parameters
  • Device keys: SALT, IPEK, TTK

Client-side certificates will be used for authentication.

Making an update request to TPS for the first time​

Mandatory path parameters: terminalSn and terminalTypeName values have to be registered and authorized in TPS. This can be done on Payments Manager.

Optional query parameters:

recordCount if not defined then TPS will send the information in a pre-configured batch size (50). Maximum limit is 1000 records.

recordType if not defined then all possible record types will be returned.

Processing logic of the update request​

  1. Terminal sends first update request to TPS. If recordType query parameter is specified then only selected data is sent, if not then all data is sent (in batches).
  2. TPS responds with a batch of requested data. TPS also provides a resumptionToken which must be saved on the terminal and sent to TPS with the next request.
  3. Terminal sends new update requests with the latest resumptionToken value until all data is received. In this case updateComplete is set to true in the response body.
  4. After some time the terminal will make a new request for the data. The terminal must also provide the resumptionToken value.
  5. In case of no data available for defined record type then updateComplete will be set to true in the response body.
  6. In case of fewer data is returned than the requested amount, update will be considered as completed. updateComplete will be set to true in the response body.
  7. If resumptionToken sent by the terminal is outdated, FLUSH action followed by INSERT actions is sent for all record types separately.

Deleting & updating records from the terminal​

For deny list, cpanToken value must be used to find the record on the terminal side. In some situations it is possible that the same cpanToken will be returned multiple times. In this case the existing value can either be overwritten or the new records can be ignored.

For permanent stoplist, transit/terminal keys, EMV parameters and device keys unique id or combination of data values must be used to find the record on the terminal side.

To update the record data, TPS returns a DELETE action with old data and an INSERT action with new data.

To delete the record, only a DELETE action with old data is returned.

Should all record data be deleted, TPS will return a single FLUSH action, followed by INSERT actions if there is any new data present.

What happens if the terminal has not updated its data for a long period of time?​

If resumptionToken is too old (configurable value, currently 30 days) then instead of updating the records TPS will send all the data to the terminal again. TPS will first respond with a record that has records.actionType = FLUSH.

NB! If records.actionType = FLUSH then existing data must NOT be deleted immediately. Instead, all new records must be downloaded first, and then it is possible to switch to new database (to avoid situations where terminal does not have any data at all).

What happens if the data download fails for some reason?​

If data download fails for terminal then it must revert all changes. New request with the same resumptionToken value must be sent to TPS. If needed then recordCount value can be set smaller to reduce load.

What happens if TPS returns INVALID_RESUMPTION_TOKEN?​

Terminal has to flush all data and send a new request without a resumption token.